home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2001 May / SGI Freeware 2001 May - Disc 1.iso / dist / fw_teTeX.idb / usr / freeware / info / web2c.info-3.z / web2c.info-3 (.txt)
GNU Info File  |  2001-01-10  |  45KB  |  835 lines
  1. This is Info file web2c.info, produced by Makeinfo version 1.68 from
  2. the input file web2c.texi.
  3. INFO-DIR-SECTION TeX
  4. START-INFO-DIR-ENTRY
  5. * Web2c: (web2c).                    TeX, Metafont, and companion programs.
  6. * bibtex: (web2c)bibtex invocation.             Maintaining bibliographies.
  7. * dmp: (web2c)dmp invocation.                   Troff->MPX (MetaPost pictures).
  8. * dvicopy: (web2c)dvicopy invocation.           Virtual font expansion
  9. * dvitomp: (web2c)dvitomp invocation.           DVI to MPX (MetaPost pictures).
  10. * dvitype: (web2c)dvitype invocation.           DVI to human-readable text.
  11. * gftodvi: (web2c)gftodvi invocation.           Generic font proofsheets.
  12. * gftopk: (web2c)gftopk invocation.             Generic to packed fonts.
  13. * gftype: (web2c)gftype invocation.             GF to human-readable text.
  14. * inimf: (web2c)inimf invocation.               Initial Metafont.
  15. * inimpost: (web2c)inimpost invocation.         Initial MetaPost.
  16. * initex: (web2c)initex invocation.             Initial TeX.
  17. * makempx: (web2c)makempx invocation.           MetaPost label typesetting.
  18. * mf: (web2c)mf invocation.                     Creating typeface families.
  19. * mft: (web2c)mft invocation.                   Prettyprinting Metafont source.
  20. * mltex: (web2c)MLTeX.                          Multi-lingual TeX.
  21. * mpost: (web2c)mpost invocation.               Creating technical diagrams.
  22. * mpto: (web2c)mpto invocation.                 MetaPost label extraction.
  23. * newer: (web2c)newer invocation.               Compare modification times.
  24. * patgen: (web2c)patgen invocation.             Creating hyphenation patterns.
  25. * pktogf: (web2c)pktogf invocation.             Packed to generic fonts.
  26. * pktype: (web2c)pktype invocation.             PK to human-readable text.
  27. * pltotf: (web2c)pltotf invocation.             Property list to TFM.
  28. * pooltype: (web2c)pooltype invocation.         Display WEB pool files.
  29. * tangle: (web2c)tangle invocation.             WEB to Pascal.
  30. * tex: (web2c)tex invocation.                   Typesetting.
  31. * tftopl: (web2c)tftopl invocation.             TFM -> property list.
  32. * vftovp: (web2c)vftovp invocation.             Virtual font -> virtual pl.
  33. * virmf: (web2c)virmf invocation.               Virgin Metafont.
  34. * virmpost: (web2c)virmpost invocation.         Virgin MetaPost.
  35. * virtex: (web2c)virtex invocation.             Virgin TeX.
  36. * vptovf: (web2c)vptovf invocation.             Virtual pl -> virtual font.
  37. * weave: (web2c)weave invocation.               WEB to TeX.
  38. END-INFO-DIR-ENTRY
  39.   This file documents the installation and use of the programs in Web2c,
  40. an implementation of Donald Knuth's TeX system.
  41.   Copyright (C) 1996, 97 K. Berry & O. Weber.
  42.   Permission is granted to make and distribute verbatim copies of this
  43. manual provided the copyright notice and this permission notice are
  44. preserved on all copies.
  45.   Permission is granted to copy and distribute modified versions of this
  46. manual under the conditions for verbatim copying, provided that the
  47. entire resulting derived work is distributed under the terms of a
  48. permission notice identical to this one.
  49.   Permission is granted to copy and distribute translations of this
  50. manual into another language, under the above conditions for modified
  51. versions, except that this permission notice may be stated in a
  52. translation
  53. File: web2c.info,  Node: weave invocation,  Next: pooltype invocation,  Prev: tangle invocation,  Up: WEB
  54. Weave: Translate WEB to TeX
  55. ===========================
  56.   Weave creates a TeX document from a WEB source file (*note WEB::.),
  57. assuming various macros defined in `webmac.tex'.   It takes care of
  58. typographic details such as page layout, indentation, and italicizing
  59. identifiers.  It also automatically gathers and outputs extensive
  60. cross-reference information.  Synopsis:
  61.      weave [OPTION]... WEBFILE[.web] [CHANGEFILE[.ch]]
  62. The output is to the basename of WEBFILE extended with `.tex'; for
  63. example, `weave /wherever/foo.web' creates `./foo.tex'.  Weave applies
  64. CHANGEFILE to WEBFILE before writing the output; by default, there is
  65. no change file.
  66.   The program accepts the following option, as well as the standard
  67. `-verbose', `-help' and `-version' (*note Common options::.):
  68.      Omit the cross-reference information: the index, the list of WEB
  69.      module names, and the table of contents (an empty `CONTENTS.tex'
  70.      file will still be written when the Weave output file is processed
  71.      by TeX using the default `webmac.tex', though).
  72.   Conventionally, WEB programmers should define the TeX `\title' macro
  73. at the beginning of the source file.  Also, to get output of only
  74. changed modules, one can say `\let\maybe=\iffalse' (usually as the
  75. first change in the change file).
  76. File: web2c.info,  Node: pooltype invocation,  Prev: weave invocation,  Up: WEB
  77. Pooltype: Display WEB pool files
  78. ================================
  79.   Pooltype shows the so-called "string number" of each string in a WEB
  80. pool file (*note WEB::.), as output by Tangle (*note tangle
  81. invocation::.), including the first 256 strings corresponding to the
  82. possible input characters.  Pooltype primarily serves as an example of
  83. WEB conventions to implementors of the TeX system.  Synopsis:
  84.      pooltype [OPTION]... POOLFILE[.pool]
  85. No path searching is done for POOLFILE.  Output is to standard output.
  86.   The only options are `--help' and `--version' (*note Common
  87. options::.).
  88.   As an example of the output, here is the (edited) output for
  89. `tex.pool':
  90.      0: "^^@"
  91.      1: "^^A"
  92.      ...
  93.      255: "^^ff"
  94.      256: "pool size"
  95.      ...
  96.      1314: "Using character substitution: "
  97.      (23617 characters in all.)
  98.   In Metafont and MetaPost, the first 256 characters are actually
  99. represented as single bytes (i.e., themselves), not in the `^^'
  100. notation.  Consider Pooltype as showing the results after conversion for
  101. output.
  102. File: web2c.info,  Node: DVI utilities,  Next: Font utilities,  Prev: WEB,  Up: Top
  103. DVI utilities
  104. *************
  105.   TeX outputs a file in "DVI" (DeVice Independent) format as a compact
  106. representation of the original document.  DVI files can be translated
  107. to meet the requirements of a real physical device, such as PostScript
  108. printers (*note Introduction: (dvips)Top.), PCL printers (see
  109. dvilj(1)), and X displays (see xdvi(1)).  In fact, DVI translators are
  110. available for virtually all common devices: see `CTAN:/dviware' (for
  111. CTAN info, *note unixtex.ftp: (kpathsea)unixtex.ftp.).
  112.   For the precise definition of the DVI file format, see (for example)
  113. the source file `web2c/dvitype.web'.
  114.   The DVI-processing programs in the Web2c distribution are not device
  115. drivers; they perform generic utility functions.
  116. * Menu:
  117. * dvicopy invocation::          Expand virtual fonts.
  118. * dvitype invocation::          DVI to human-readable text.
  119. File: web2c.info,  Node: dvicopy invocation,  Next: dvitype invocation,  Up: DVI utilities
  120. DVIcopy: Canonicalize virtual font references
  121. =============================================
  122.   DVIcopy reads a DVI file, expands any references to virtual fonts
  123. (*note Virtual fonts: (dvips)Virtual fonts.) to base fonts, and writes
  124. the resulting DVI file.  Thus you can use virtual fonts even if your DVI
  125. processor does not support them, by passing the documents through
  126. DVIcopy first.  Synopsis:
  127.      dvicopy [OPTION]... [INDVI[.dvi] [OUTDVI[.dvi]]]
  128.   DVIcopy reads standard input if INDVI is not specified, and writes
  129. standard output if OUTDVI is not specified.
  130.   The program accepts the following options, as well as the standard
  131. `-help' and `-version' (*note Common options::.):
  132. `-magnification=INTEGER'
  133.      Override existing magnification in INDVI with INTEGER; 1000
  134.      specifies no magnification.  This is equivalent to setting TeX's
  135.      `\mag' parameter.
  136. `-max-pages=N'
  137.      Process N pages; default is one million.
  138. `-page-start=PAGE-SPEC'
  139.      Start at the first page matching PAGE-SPEC, which is one or more
  140.      (signed) integers separated by periods, corresponding to TeX's
  141.      `\count0...9' parameters at `\shipout' time; `*' matches anything.
  142.      Examples: `3', `1.*.-4'.
  143. File: web2c.info,  Node: dvitype invocation,  Prev: dvicopy invocation,  Up: DVI utilities
  144. DVItype: Plain text transliteration of DVI files
  145. ================================================
  146.   DVItype translates a DeVice Independent (DVI) file (as output by TeX,
  147. for example) to a plain text file that humans can read.  It also serves
  148. as a DVI-validating program, i.e., if DVItype can read a file, it's
  149. correct.  Synopsis:
  150.      dvitype [OPTION]... DVIFILE[.dvi]
  151. DVItype does not read any bitmap files, but it does read TFM files for
  152. fonts referenced in DVIFILE.  The usual places are searched (*note
  153. Supported file formats: (kpathsea)Supported file formats.).  To see all
  154. the relevant paths, set the environment variable `KPATHSEA_DEBUG' to
  155. `-1' before running the program.
  156.   Output goes to standard output.
  157.   The program accepts the following options, as well as the standard
  158. `-help' and `-version' (*note Common options::.):
  159. `-dpi=REAL'
  160.      Do pixel movement calculations at REAL pixels per inch; default
  161.      300.0.
  162. `-magnification=INTEGER'
  163.      Override existing magnification in INDVI with INTEGER; 1000
  164.      specifies no magnification.  This is equivalent to setting TeX's
  165.      `\mag' parameter.
  166. `-max-pages=N'
  167.      Process N pages; default is one million.
  168. `-output-level=N'
  169.      Verbosity level of output, from 0 to 4 (default 4):
  170.         * 0: Global document information only.
  171.         * 1: Most DVI commands included, and typeset characters
  172.           summarized.
  173.         * 2: Character and movement commands explicitly included.
  174.         * 3: DVI stack and current position calculations included.
  175.         * 4: Same information as level 3, but DVItype does random
  176.           positioning in the file, reading the DVI postamble first.
  177. `-page-start=PAGE-SPEC'
  178.      Start at the first page matching PAGE-SPEC, which is one or more
  179.      (signed) integers separated by periods, corresponding to TeX's
  180.      `\count0...9' parameters at `\shipout' time; `*' matches anything.
  181.      Examples: `1', `5.*.-9'.
  182. `-show-opcodes'
  183.      Show numeric opcode values (in decimal) for DVI commands, in braces
  184.      after the command name. This can help in debugging DVI utilities.
  185.      We use decimal because in the DVI format documentation (in
  186.      `dvitype.web', among others) the opcodes are shown in decimal.
  187. * Menu:
  188. * dvitype output example::
  189. File: web2c.info,  Node: dvitype output example,  Up: dvitype invocation
  190. DVItype output example
  191. ----------------------
  192.   As an example of the output from DVItype (see section above), here is
  193. its (abridged) translation of the `story.dvi' resulting from running
  194. the example in `The TeXbook', with `-output-level=4' and
  195. `-show-opcodes' on.
  196.      ...
  197.      Options selected:
  198.        Starting page = *
  199.        Maximum number of pages = 1000000
  200.        Output level = 4 (the works)
  201.        Resolution = 300.00000000 pixels per inch
  202.      numerator/denominator=25400000/473628672
  203.      magnification=1000;       0.00006334 pixels per DVI unit
  204.      ' TeX output 1992.05.17:0844'
  205.      Postamble starts at byte 564.
  206.      maxv=43725786, maxh=30785863, maxstackdepth=3, totalpages=1
  207.      Font 33: cmsl10---loaded at size 655360 DVI units
  208.      Font 23: cmbx10---loaded at size 655360 DVI units
  209.      Font 0: cmr10---loaded at size 655360 DVI units
  210.      
  211.      42: beginning of page 1
  212.      87: push {141}
  213.      level 0:(h=0,v=0,w=0,x=0,y=0,z=0,hh=0,vv=0)
  214.      88: down3 -917504 {159} v:=0-917504=-917504, vv:=-58
  215.      92: pop {142}
  216.      ...
  217.      104: putrule {137} height 26214, width 30785863 (2x1950 pixels)
  218.      113: down3 5185936 {159} v:=655360+5185936=5841296, vv:=370
  219.      117: push {141}
  220.      level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370)
  221.      118: right4 12265425 {146} h:=0+12265425=12265425, hh:=777
  222.      [ ]
  223.      123: fntdef1 23 {243}: cmbx10
  224.      145: fntnum23 {194} current font is cmbx10
  225.      146: setchar65 h:=12265425+569796=12835221, hh:=813
  226.      147: w3 251220 {150} h:=12835221+251220=13086441, hh:=829
  227.      151: setchar83 h:=13086441+418700=13505141, hh:=856
  228.      ...
  229.      164: setchar82 h:=17448202+565245=18013447, hh:=1142
  230.      165: x0 -62805 {152} h:=18013447-62805=17950642, hh:=1138
  231.      166: setchar89 h:=17950642+569796=18520438, hh:=1174
  232.      [A SHORT STORY]
  233.      167: pop {142}
  234.      level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370)
  235.      ...
  236.      550: pop {142}
  237.      level 0:(h=0,v=42152922,w=0,x=0,y=0,z=0,hh=0,vv=2670)
  238.      551: down3 1572864 {159} v:=42152922+1572864=43725786, vv:=2770
  239.      555: push {141}
  240.      level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770)
  241.      556: right4 15229091 {146} h:=0+15229091=15229091, hh:=965
  242.      561: setchar49 h:=15229091+327681=15556772, hh:=986
  243.      [ 1]
  244.      562: pop {142}
  245.      level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770)
  246.      563: eop {140}
  247.   Explanation:
  248.    * The DVItype options are recorded at the beginning, followed by
  249.      global information about the document, including fonts used.
  250.    * Each DVI command is preceded by its byte position in the file
  251.      (`42:', `87:', ...), and (because of the `-show-opcodes') followed
  252.      by its decimal opcode value in braces (`{141}', `{142}', ...).
  253.    * The `level' lines record information about the DVI stack; `h' and
  254.      `v' define the current position in DVI units, while `hh' and `vv'
  255.      are the same in pixels.
  256.    * Text sequences are summarized in brackets, as in `[A SHORT STORY]'
  257.      and the `[ 1]'.
  258. File: web2c.info,  Node: Font utilities,  Next: Legalisms,  Prev: DVI utilities,  Up: Top
  259. Font utilities
  260. **************
  261.   The Web2c programs described here convert between various TeX-related
  262. font formats; the first section below briefly describes the formats.
  263. GFtoPK is the only one that is routinely used, as Metafont outputs GF
  264. format, but it's most efficient for device drivers to use PK.
  265.   The precise definitions of the PK, GF, TFM, PL, VF, and VPL formats
  266. mentioned below are in the source files that read them; `pktype.web',
  267. `gftype.web', `tftopl.web', etc.
  268. * Menu:
  269. * Font file formats::       Explanations of GF, PK, TFM, VF, ...
  270. * gftopk invocation::       GF -> PK (compact)
  271. * pktogf invocation::       PK -> GF (expand).
  272. * pktype invocation::       PK -> human-readable text.
  273. * gftype invocation::       GF -> human-readable text.
  274. * tftopl invocation::       TFM -> PL (for editing TFM).
  275. * pltotf invocation::       PL -> TFM (make editing results usable).
  276. * vftovp invocation::       VF -> VPL (tftopl for virtual fonts).
  277. * vptovf invocation::       VPL -> VF (pltotf for virtual fonts).
  278. * Font utilities available elsewhere:: Type 1, BDF, editors, etc.
  279. File: web2c.info,  Node: Font file formats,  Next: gftopk invocation,  Up: Font utilities
  280. Font file formats
  281. =================
  282.   (For another perspective on this, *note Font concepts: (dvips)Font
  283. concepts.).
  284.   Font files come in several varieties, with suffixes like:
  285.      .tfm  .*pk  .*gf  .*pxl (obsolete)  .pl  .mf  .vf  .vpl
  286. Each represents a file format.
  287.   A TFM (TeX font metric) file is a compact binary file that contains
  288. information about each character in a font, about combinations of
  289. characters within that font, and about the font as a whole.  The font
  290. metric information contained in TFM files is device-independent units is
  291. used by TeX to do typesetting.  Unlike the bitmap (raster) fonts
  292. described below, TFM font files contain no information about the shapes
  293. of characters.  They describe rectangular areas and combinations
  294. thereof, but not what will eventually be printed in those areas.
  295.   Since TeX does scaling calculations, one TFM file serves for all
  296. magnifications of a given typeface.  On the other hand, the best printed
  297. results are obtained when magnified (or reduced fonts) are not produced
  298. geometrically (as done by PostScript, for example) but rather optically,
  299. with each size a separate design (as done with Computer Modern and the
  300. EC fonts, for example); then a separate TFM file is needed for each
  301. size.
  302.   At any rate, TeX produces a DVI (DeVice Independent) file from your
  303. source document.  In order to print DVI files on real devices, you need
  304. font files defining digitized character shapes and other data.  Then
  305. previewers and printer-driver programs can translate your DVI files into
  306. something usable by your monitor or printer.  Bitmap fonts come with
  307. suffixes such as `.600pk' or `.600gf' or `.3000pxl', where the `600' is
  308. the horizontal dots-per-inch resolution at which the font was produced,
  309. and the `pk' or `gf' or `pxl' indicates the font format.  Outline fonts
  310. in PostScript Type 1 format have suffixes such as `.pfa' or `.pfb'.
  311.   Fonts in pk (packed) format are in the tightly packed raster format
  312. that is pretty much the standard today.  They take up less space than
  313. fonts in the gf (generic font) format that Metafont generates, and far
  314. less space than fonts in pxl format.  Fonts in pxl format take up gross
  315. amounts of disk space and permit only 128 characters.  They are
  316. obsolete.
  317.   Font files with the `.pl' (property list) suffix are the plain text
  318. (human-readable) analog of the binary `.tfm' files.  The TFtoPL and
  319. PLtoTF programs convert between the two formats (*note tftopl
  320. invocation::. and *Note pltotf invocation::).
  321.   Font files with the `.mf' suffix are in Metafont source format.
  322. These are the files used by Metafont to generate rastered fonts for
  323. specific typefaces at specific magnifications for the specific
  324. resolution and type of mapping used by your device.
  325.   The suffix `.vf' identifies "virtual font" files, for which `.vpl' is
  326. the human-readable analog.  *Note vftovp invocation:: and *Note vptovf
  327. invocation::.  For further discussion of virtual fonts, see
  328. `CTAN:/doc/virtual-fonts.knuth', `CTAN:/help/virtualfonts.txt', and
  329. *Note Virtual fonts: (dvips)Virtual fonts.
  330.   (This section is based on documentation in the original Unix TeX
  331. distribution by Pierre MacKay and Elizabeth Tachikawa.)
  332. File: web2c.info,  Node: gftopk invocation,  Next: pktogf invocation,  Prev: Font file formats,  Up: Font utilities
  333. GFtoPK: Generic to packed font conversion
  334. =========================================
  335.   GFtoPK converts a generic font (GF) file output by, for example,
  336. Metafont (*note mf invocation::.) to a packed font (PK) file.  PK files
  337. are considerably smaller than the corresponding gf files, so they are
  338. generally the bitmap font format of choice.  Some DVI-processing
  339. programs, notably Dvips, only support PK files and not GF files.
  340. Synopsis:
  341.      gftopk [OPTION]... GFNAME.DPI[gf] [PKFILE]
  342. The font GFNAME is searched for in the usual places (*note Glyph
  343. lookup: (kpathsea)Glyph lookup.).  To see all the relevant paths, set
  344. the environment variable `KPATHSEA_DEBUG' to `-1' before running the
  345. program.
  346.   The suffix `gf' is supplied if not already present.  This suffix is
  347. not an extension; no `.' precedes it: for instance, `cmr10.600gf'.
  348.   If PKFILE is not specified, the output is written to the basename of
  349. `GFNAME.DPIpk', e.g., `gftopk /wherever/cmr10.600gf' creates
  350. `./cmr10.600pk'.
  351.   The only options are `--verbose', `--help', and `--version' (*note
  352. Common options::.).
  353. File: web2c.info,  Node: pktogf invocation,  Next: pktype invocation,  Prev: gftopk invocation,  Up: Font utilities
  354. PKtoGF: Packed to generic font conversion
  355. =========================================
  356.   PKtoGF converts a packed font (PK) file to a generic font (GF) file.
  357. Since PK format is much more compact than GF format, the most likely
  358. reason to do this is to run GFtype (*note gftype invocation::.) on the
  359. result, so you can see the bitmap images.  Also, a few old utility
  360. programs do not support PK format.  Synopsis:
  361.      pktogf [OPTION]... PKNAME.DPI[pk] [GFFILE]
  362. The font PKNAME is searched for in the usual places (*note Glyph
  363. lookup: (kpathsea)Glyph lookup.).  To see all the relevant paths, set
  364. the environment variable `KPATHSEA_DEBUG' to `-1' before running the
  365. program.
  366.   The suffix `pk' is supplied if not already present.  This suffix is
  367. not an extension; no `.' precedes it: for instance, `cmr10.600pk'.
  368.   If GFFILE is not specified, the output is written to the basename of
  369. `PKNAME.DPIgf', e.g., `pktogf /wherever/cmr10.600pk' creates
  370. `./cmr10.600gf'.
  371.   The only options are `--verbose', `--help', and `--version' (*note
  372. Common options::.).
  373. File: web2c.info,  Node: pktype invocation,  Next: gftype invocation,  Prev: pktogf invocation,  Up: Font utilities
  374. PKtype: Plain text transliteration of packed fonts
  375. ==================================================
  376.   PKtype translates a packed font (PK) bitmap file (as output by GFtoPK,
  377. for example) to a plain text file that humans can read.  It also serves
  378. as a PK-validating program, i.e., if PKtype can read a file, it's
  379. correct.  Synopsis:
  380.      pktype PKNAME.DPI[pk]
  381.   The font PKNAME is searched for in the usual places (*note Glyph
  382. lookup: (kpathsea)Glyph lookup.).  To see all the relevant paths, set
  383. the environment variable `KPATHSEA_DEBUG' to `-1' before running the
  384. program.
  385.   The suffix `pk' is supplied if not already present.  This suffix is
  386. not an extension; no `.' precedes it: for instance, `cmr10.600pk'.
  387.   The translation is written to standard output.
  388.   The only options are `-help' and `-version' (*note Common options::.).
  389.   As an example of the output, here is the (abridged) translation of the
  390. letter `K' in `cmr10', as rendered at 600dpi with the mode `ljfour'
  391. from `modes.mf' (available from `ftp://ftp.tug.org/tex/modes.mf').
  392.      955:  Flag byte = 184  Character = 75  Packet length = 174
  393.        Dynamic packing variable = 11
  394.        TFM width = 815562  dx = 4259840
  395.        Height = 57  Width = 57  X-offset = -3  Y-offset = 56
  396.        [2]23(16)17(8)9(25)11(13)7(27)7(16)7(28)4(18)7(28)2(20)7(27)...
  397.        ...
  398.        (14)9(24)12(5)[2]23(13)21
  399. Explanation:
  400. `955'
  401.      The byte position in the file where this character starts.
  402. `Flag byte'
  403. `Dynamic packing variable'
  404.      Related to the packing for this character; see the source code.
  405. `Character'
  406.      The character code, in decimal.
  407. `Packet length'
  408.      The total length of this character definition, in bytes.
  409. `TFM width'
  410.      The device-independent (TFM) width of this character.  It is 2^24
  411.      times the ratio of the true width to the font's design size.
  412.      The device-dependent width, in "scaled pixels", i.e., units of
  413.      horizontal pixels times 2^16.
  414. `Height'
  415. `Width'
  416.      The bitmap height and width, in pixels.
  417. `X-offset'
  418. `Y-offset'
  419.      Horizontal and vertical offset from the upper left pixel to the
  420.      reference (origin) pixel for this character, in pixels (right and
  421.      down are positive).  The "reference pixel" is the pixel that
  422.      occupies the unit square in Metafont; the Metafont reference point
  423.      is the lower left hand corner of this pixel. Put another way, the
  424.      x-offset is the negative of the left side bearing; the right side
  425.      bearing is the horizontal escapement minus the bitmap width plus
  426.      the x-offset.
  427. `[2]23(16)...'
  428.      Finally, run lengths of black pixels alternate with parenthesized
  429.      run lengths of white pixels, and brackets indicate a repeated row.
  430. File: web2c.info,  Node: gftype invocation,  Next: tftopl invocation,  Prev: pktype invocation,  Up: Font utilities
  431. GFtype: Plain text transliteration of generic fonts
  432. ===================================================
  433.   GFtype translates a generic font (GF) bitmap file (as output by
  434. Metafont, for example) to a plain text file that humans can read.  It
  435. also serves as a GF-validating program, i.e., if GFtype can read a file,
  436. it's correct.  Synopsis:
  437.      gftype [OPTION]... GFNAME.DPI[gf]
  438.   The font GFNAME is searched for in the usual places (*note Glyph
  439. lookup: (kpathsea)Glyph lookup.).  To see all the relevant paths, set
  440. the environment variable `KPATHSEA_DEBUG' to `-1' before running the
  441. program.
  442.   The suffix `gf' is supplied if not already present.  This suffix is
  443. not an extension; no `.' precedes it: for instance, `cmr10.600gf'.
  444.   The translation is written to standard output.
  445.   The program accepts the following options, as well as the standard
  446. `-help' and `-version' (*note Common options::.):
  447. `-images'
  448.      Show the characters' bitmaps using asterisks and spaces.
  449. `-mnemonics'
  450.      Translate all commands in the GF file.
  451.   As an example of the output, here is the (abrdiged) translation of the
  452. letter `K' in `cmr10', as rendered at 600dpi with the mode `ljfour'
  453. from `modes.mf' (available from `ftp://ftp.tug.org/tex/modes.mf'), with
  454. both `-mnemonics' and `-images' enabled.
  455.   GFtype outputs the information about a character in two places: a main
  456. definition and a one-line summary at the end. We show both.  Here is the
  457. main definition:
  458.      2033: beginning of char 75: 3<=m<=60 0<=n<=56
  459.      (initially n=56) paint (0)24(12)20
  460.      2043: newrow 0 (n=55) paint 24(12)20
  461.      2047: newrow 0 (n=54) paint 24(12)20
  462.      2051: newrow 0 (n=53) paint 24(12)20
  463.      2055: newrow 7 (n=52) paint 10(21)13
  464.      2059: newrow 8 (n=51) paint 8(23)9
  465.      ...
  466.      2249: newrow 8 (n=5) paint 8(23)11
  467.      2253: newrow 7 (n=4) paint 10(22)12
  468.      2257: newrow 0 (n=3) paint 24(11)22
  469.      2261: newrow 0 (n=2) paint 24(11)22
  470.      2265: newrow 0 (n=1) paint 24(11)22
  471.      2269: newrow 0 (n=0) paint 24(11)22
  472.      2273: eoc
  473.      .<--This pixel's lower left corner is at (3,57) in METAFONT coordinates
  474.      ************************            ********************
  475.      ************************            ********************
  476.      ************************            ********************
  477.      ************************            ********************
  478.             **********                     *************
  479.              ********                       *********
  480.      ...
  481.              ********                       ***********
  482.             **********                      ************
  483.      ************************           **********************
  484.      ************************           **********************
  485.      ************************           **********************
  486.      ************************           **********************
  487.      .<--This pixel's upper left corner is at (3,0) in METAFONT coordinates
  488. Explanation:
  489. `2033'
  490. `2043'
  491. `...'
  492.      The byte position in the file where each GF command starts.
  493. `beginning of char 75'
  494.      The character code, in decimal.
  495. `3<=m<=60 0<=n<=56'
  496.      The character's bitmap lies between 3 and 60 (inclusive)
  497.      horizontally, and between 0 and 56 (inclusive) vertically. (m is a
  498.      column position and n is a row position.)  Thus, 3 is the left side
  499.      bearing.  The right side bearing is the horizontal escapement
  500.      (given below) minus the maximum m.
  501. `(initially n=56) paint (0)24(12)20'
  502.      The first row of pixels: 0 white pixels, 24 black pixels, 12 white
  503.      pixels, etc.
  504. `newrow 0 (n=55) paint 24(12)20'
  505.      The second row of pixels, with zero leading white pixels on the
  506.      row.
  507. `eoc'
  508.      The end of the main character definition.
  509.   Here is the GF postamble information that GFtype outputs at the end:
  510.      Character 75: dx 4259840 (65), width 815562 (64.57289), loc 2033
  511.   Explanation:
  512.      The device-dependent width, in "scaled pixels", i.e., units of
  513.      horizontal pixels times 2^16.  The `(65)' is simply the same number
  514.      rounded.  If the vertical escapement is nonzero, it would appear
  515.      here as a `dy' value.
  516. `width'
  517.      The device-independent (TFM) width of this character.  It is 2^24
  518.      times the ratio of the true width to the font's design size.  The
  519.      `64.57289' is the same number converted to pixels.
  520. `loc'
  521.      The byte position in the file where this character starts.
  522. File: web2c.info,  Node: tftopl invocation,  Next: pltotf invocation,  Prev: gftype invocation,  Up: Font utilities
  523. TFtoPL: TeX font metric to property list conversion
  524. ===================================================
  525.   TFtoPL translates a TeX font metric (TFM, *note Metric files:
  526. (dvips)Metric files.) file (as output by Metafont, for example) to
  527. "property list format" (a list of parenthesized items describing the
  528. font) that humans can edit or read.  This program is mostly used by
  529. people debugging TeX implementations, writing font utilities, etc.
  530. Synopsis:
  531.      tftopl [OPTION]... TFMNAME[.tfm] [PLFILE[.pl]]
  532.   The font TFMNAME (extended with `.tfm' if necessary) is searched for
  533. in the usual places (*note Supported file formats: (kpathsea)Supported
  534. file formats.).  To see all the relevant paths, set the environment
  535. variable `KPATHSEA_DEBUG' to `-1' before running the program.
  536.   If PLFILE (which is extended with `.pl' if necessary) is not
  537. specified, the property list file is written to standard output.  The
  538. property list file can be converted back to TFM format by the companion
  539. program TFtoPL (see the next section).
  540.   The program accepts the following option, as well as the standard
  541. `-verbose', `-help' and `-version' (*note Common options::.):
  542. `-charcode-format=TYPE'
  543.      Output character codes in the PL file according to TYPE: either
  544.      `octal' or `ascii'.  Default is `ascii' for letters and digits,
  545.      octal for all other characters.  Exception: if the font's coding
  546.      scheme starts with `TeX math sy' or `TeX math ex', all character
  547.      codes are output in octal.
  548.      In `ascii' format, character codes that correspond to graphic
  549.      characters, except for left and right parentheses, are output as a
  550.      `C' followed by the single character: `C K', for example.  In
  551.      octal format, character codes are output as the letter `O' followed
  552.      by octal digits, as in `O 113' for `K'.
  553.      `octal' format is useful for symbol and other non-alphabetic fonts,
  554.      where using ASCII characters for the character codes is merely
  555.      confusing.
  556.   As an example of the output, here is the (abridged) property list
  557. translation of `cmr10.tfm':
  558.      (FAMILY CMR)
  559.      (FACE O 352)
  560.      (CODINGSCHEME TEX TEXT)
  561.      (DESIGNSIZE R 10.0)
  562.      (COMMENT DESIGNSIZE IS IN POINTS)
  563.      (COMMENT OTHER SIZES ARE MULTIPLES OF DESIGNSIZE)
  564.      (CHECKSUM O 11374260171)
  565.      (FONTDIMEN
  566.         (SLANT R 0.0)
  567.         (SPACE R 0.333334)
  568.         (STRETCH R 0.166667)
  569.         (SHRINK R 0.111112)
  570.         (XHEIGHT R 0.430555)
  571.         (QUAD R 1.000003)
  572.         (EXTRASPACE R 0.111112)
  573.         )
  574.      (LIGTABLE
  575.         ...
  576.         (LABEL C f)
  577.         (LIG C i O 14)
  578.         (LIG C f O 13)
  579.         (LIG C l O 15)
  580.         (KRN O 47 R 0.077779)
  581.         (KRN O 77 R 0.077779)
  582.         (KRN O 41 R 0.077779)
  583.         (KRN O 51 R 0.077779)
  584.         (KRN O 135 R 0.077779)
  585.         (STOP)
  586.         ...
  587.         )
  588.      ...
  589.      (CHARACTER C f
  590.         (CHARWD R 0.305557)
  591.         (CHARHT R 0.694445)
  592.         (CHARIC R 0.077779)
  593.         (COMMENT
  594.            (LIG C i O 14)
  595.            (LIG C f O 13)
  596.            (LIG C l O 15)
  597.            (KRN O 47 R 0.077779)
  598.            (KRN O 77 R 0.077779)
  599.            ...
  600.            )
  601.         )
  602.      ...
  603.   As you can see, the general format is a list of parenthesized
  604. "properties", nested where necessary.
  605.    * The first few items (`FAMILY', `FACE', and so on) are the
  606.      so-called "headerbyte" information from Metafont, giving general
  607.      information about the font.
  608.    * The `FONTDIMEN' property defines the TeX `\fontdimen' values.
  609.    * The `LIGTABLE' property defines the ligature and kerning table.
  610.      `LIG' properties define ligatures: in the example above, an `f'
  611.      (in the `LABEL') followed by an `i' is a ligature, i.e., a
  612.      typesetting program like TeX replaces those two consecutive
  613.      characters by the character at position octal '014 in the current
  614.      font--presumably the `fi' ligature.  `KRN' properties define
  615.      kerns: if an `f' is followed by character octal '047 (an
  616.      apostrophe), TeX inserts a small amount of space between them:
  617.      0.077779 times the design size the font was loaded at (about
  618.      three-quarters of a printer's point by default in this case, or
  619.      .001 inches).
  620.    * The `CHARACTER' property defines the dimensions of a character: its
  621.      width, height, depth, and italic correction, also in design-size
  622.      units, as explained in the previous item.  For our example `f',
  623.      the depth is zero, so that property is omitted.  TFtoPL also
  624.      inserts any kerns and ligatures for this character as a comment.
  625. File: web2c.info,  Node: pltotf invocation,  Next: vftovp invocation,  Prev: tftopl invocation,  Up: Font utilities
  626. PLtoTF: Property list to TeX font metric conversion
  627. ===================================================
  628.   PLtoTF translates a property list file (as output by TFtoPL, for
  629. example) to TeX font metric (TFM, *note Metric files: (dvips)Metric
  630. files.)  format.  It's much easier for both programs and humans to
  631. create the (plain text) property list files and let PLtoTF take care of
  632. creating the binary TFM equivalent than to output TFM files directly.
  633. Synopsis:
  634.      pltotf [OPTION]... PLFILE[.pl] [TFMFILE[.tfm]]
  635.   If TFMFILE (extended with `.tfm' if necessary) is not specified, the
  636. TFM file is written to the basename of `PLFILE.tfm', e.g., `pltotf
  637. /wherever/cmr10.pl' creates `./cmr10.tfm'.  (Since TFM files are
  638. binary, writing to standard output by default is undesirable.)
  639.   The only options are `-verbose', `-help', and `-version' (*note
  640. Common options::.).
  641.   For an example of property list format, see the previous section.
  642. File: web2c.info,  Node: vftovp invocation,  Next: vptovf invocation,  Prev: pltotf invocation,  Up: Font utilities
  643. VFtoVP: Virtual font to virtual property lists
  644. ==============================================
  645.   VFtoVP translates a virtual font metric (VF, *note Virtual fonts:
  646. (dvips)Virtual fonts.) file and its accompanying TeX font metric (TFM,
  647. *note Metric files: (dvips)Metric files.) file (as output by VPtoVF, for
  648. example) to "virtual property list format" (a list of parenthesized
  649. items describing the virtual font) that humans can edit or read.  This
  650. program is mostly used by people debugging virtual font utilities.
  651. Synopsis:
  652.      vftovp [OPTION]... VFNAME[.vf] [TFMNAME[.tfm] [VPLFILE[.vpl]]]
  653.   The fonts VFNAME and TFMNAME (extended with `.vf' and `.tfm' if
  654. necessary) are searched for in the usual places (*note Supported file
  655. formats: (kpathsea)Supported file formats.).  To see all the relevant
  656. paths, set the environment variable `KPATHSEA_DEBUG' to `-1' before
  657. running the program.  If TFMNAME is not specified, VFNAME (without a
  658. trailing `.vf') is used.
  659.   If VPLFILE (extended with `.vpl' if necessary) is not specified, the
  660. property list file is written to standard output.  The property list
  661. file can be converted back to VF and TFM format by the companion
  662. program VFtoVP (see the next section).
  663.   The program accepts the following option, as well as the standard
  664. `-verbose', `-help' and `-version' (*note Common options::.):
  665. `-charcode-format=TYPE'
  666.      Output character codes in the PL file according to TYPE: either
  667.      `octal' or `ascii'.  Default is `ascii' for letters and digits,
  668.      octal for all other characters.  Exception: if the font's coding
  669.      scheme starts with `TeX math sy' or `TeX math ex', all character
  670.      codes are output in octal.
  671.      In `ascii' format, character codes that correspond to graphic
  672.      characters, except for left and right parentheses, are output as a
  673.      `C' followed by the single character: `C K', for example.  In
  674.      octal format, character codes are output as the letter `O' followed
  675.      by octal digits, as in `O 113' for `K'.
  676.      `octal' format is useful for symbol and other non-alphabetic fonts,
  677.      where using ASCII characters for the character codes is merely
  678.      confusing.
  679. File: web2c.info,  Node: vptovf invocation,  Next: Font utilities available elsewhere,  Prev: vftovp invocation,  Up: Font utilities
  680. VPtoVF: Virtual property lists to virtual font
  681. ==============================================
  682.   VPtoVF translates a virtual property list file (as output by VFtoVP,
  683. for example) to virtual font (VF, *note Virtual fonts: (dvips)Virtual
  684. fonts.) and TeX font metric (TFM, *note Metric files: (dvips)Metric
  685. files.) files.  It's much easier for both programs and humans to create
  686. the (plain text) property list files and let VPtoVF take care of
  687. creating the binary VF and TFM equivalents than to output them
  688. directly.  Synopsis:
  689.      vptovf [OPTION]... VPLFILE[.vpl] [VFFILE[.vf] [TFMFILE[.tfm]]]
  690.   If VFFILE (extended with `.vf' if necessary) is not specified, the VF
  691. file is written to the basename of `VPLFILE.vf'; similarly for TFMFILE.
  692. For example, `vptovf /wherever/ptmr.vpl' creates `./ptmr.vf' and
  693. `./ptmr.tfm'.
  694.   The only options are `-verbose', `-help', and `-version' (*note
  695. Common options::.).
  696. File: web2c.info,  Node: Font utilities available elsewhere,  Prev: vptovf invocation,  Up: Font utilities
  697. Font utilities available elsewhere
  698. ==================================
  699.   The Web2c complement of font utilities merely implements a few basic
  700. conversions.  Many other more sophisticated font utilities exist; most
  701. are in `CTAN:/fonts/utilities' (for CTAN info, *note unixtex.ftp:
  702. (kpathsea)unixtex.ftp.).  Here are some of the most commonly-requested
  703. items:
  704.    * AFM (Adobe font metric) to TFM conversion: *note Invoking afm2tfm:
  705.      (dvips)Invoking afm2tfm., and `CTAN:/fonts/utilities/afmtopl'.
  706.    * BDF (the X bitmap format) conversion:
  707.      `ftp://ftp.tug.org/tex/bdf.tar.gz'.
  708.    * Editing of bitmap fonts: Xbfe from the GNU font utilities mentioned
  709.      below; the X BDF-editing programs available from
  710.      `ftp://ftp.x.org/R5contrib/xfed.tar.Z' and
  711.      `ftp://ftp.x.org/R5contrib/xfedor.tar.Z'; and finally, if your
  712.      fonts have only 128 characters, you can use the old `gftopxl',
  713.      `pxtoch', and `chtopx' programs from `ftp://ftp.tug.org/tex/web'.
  714.    * PK bitmaps from PostScript fonts: gsftopk from the `xdvik'
  715.      distribution or from `CTAN:/fonts/utilities/gsftopk';
  716.      alternatively, `ps2pk', from `CTAN:/fonts/utilities/ps2pk'.
  717.    * PostScript Type 1 font format conversion (i.e., between PFA and PFB
  718.      formats): `ftp://ftp.tug.org/tex/t1utils.tar.gz'.
  719.    * Scanned image conversion: the (aging) GNU font utilities convert
  720.      type specimen images to Metafont, PostScript, etc.:
  721.      `ftp://prep.ai.mit.edu/pub/gnu/fontutils-0.6.tar.gz'.
  722.    * Virtual font creation: `CTAN:/fonts/utilities/fontinst'.
  723. File: web2c.info,  Node: Legalisms,  Next: References,  Prev: Font utilities,  Up: Top
  724. Legalisms
  725. *********
  726.   In general, each file has its own copyright notice stating the copying
  727. permissions for that file.  Following is a summary.
  728.   The Web2c system itself and most of the original WEB source files are
  729. public domain.
  730.   `tex.web', the MLTeX code, `mf.web', and `bibtex.web', are
  731. copyrighted by their authors.  They may be copied verbatim, but may be
  732. modified only through a `.ch' file.
  733.   MetaPost-related files, including `mp.web' itself, are copyrighted
  734. under X-like terms; the precise notice is included below.
  735.   Finally, almost all of the Kpathsea library is covered by the GNU
  736. Library General Public License, but part of one file is covered by the
  737. regular GNU General Public License (*note Introduction:
  738. (kpathsea)Introduction.).  Therefore, the *binaries* resulting from a
  739. standard Web2c compilation are also covered by the GPL; so if you
  740. (re)distribute the binaries, you must also (offer to) distribute the
  741. complete source that went into those binaries.  See the files `COPYING'
  742. and `COPYING.LIB' for complete details on the GPL and LGPL.
  743.   The following notice must be included by the terms of the MetaPost
  744. copyright.
  745.      Permission to use, copy, modify, and distribute this software and
  746.      its documentation for any purpose and without fee is hereby
  747.      granted, provided that the above copyright notice appear in all
  748.      copies and that both that the copyright notice and this permission
  749.      notice and warranty disclaimer appear in supporting documentation,
  750.      and that the names of AT&T Bell Laboratories or any of its
  751.      entities not be used in advertising or publicity pertaining to
  752.      distribution of the software without specific, written prior
  753.      permission.
  754.      AT&T disclaims all warranties with regard to this software,
  755.      including all implied warranties of merchantability and fitness.
  756.      In no event shall AT&T be liable for any special, indirect or
  757.      consequential damages or any damages whatsoever resulting from
  758.      loss of use, data or profits, whether in an action of contract,
  759.      negligence or other tortious action, arising out of or in
  760.      connection with the use or performance of this software.
  761. File: web2c.info,  Node: References,  Next: Index,  Prev: Legalisms,  Up: Top
  762. References
  763. **********
  764.   1. Kpathsea: *Note Introduction: (kpathsea)Top.
  765.   2. Dvips and Afm2tfm: *Note Introduction: (dvips)Top.
  766.   3. For a bibliography of formal articles and technical reports on the
  767.      TeX project, see the books `TeX: The Program' or `Metafont: The
  768.      Program' cited below.
  769.   4. TUGboat: `ftp://ftp.math.utah.edu/pub/tex/bib/tugboat.bib'.
  770.   5. TeX and computer typesetting in general:
  771.      `ftp://ftp.math.utah.edu/pub/tex/bib/texbook1.bib'.
  772.   6. [Bil87] Neenie Billawala.  Write-white printing engines and tuning
  773.      fonts with Metafont.  `TUGboat', 8(1):29, April 1987.
  774.   7. [GMS94] Michel Goossens, Frank Mittelbach, and Alexander Samarin.
  775.      `The LaTeX Companion'.  Addison-Wesley, Reading, MA, USA, 1994.
  776.   8. [Hob89] John D. Hobby.  A Metafont-like System with PostScript
  777.      Output.  `TUGboat', 10(4):505-512, December 1989.
  778.   9. [Hob92] John D. Hobby.  A User's Manual for MetaPost.  Technical
  779.      Report CSTR-162, AT&T Bell Laboratories, 1992.
  780.  10. [Hob93] John D. Hobby.  Drawing Graphs with MetaPost.  Technical
  781.      Report CSTR-164, AT&T Bell Laboratories, 1993.
  782.  11. [HS91] Samuel P. Harbison and Guy L. Steele Jr.  `C--A Reference
  783.      Manual'.  Prentice-Hall, Englewood Cliffs, NJ 07632, USA, third
  784.      edition, 1991.  An authoritative reference to C programming
  785.      language, and a good companion to   Kernighan and Ritchie.
  786.  12. [KL93] Donald E. Knuth and Silvio Levy.  `The CWEB System of
  787.      Structured Documentation, Version 3.0'.  Addison-Wesley, Reading,
  788.      MA, USA, 1993.
  789.  13. [Knu84] Donald E. Knuth.  A Torture Test for TeX.  Report No.
  790.      STAN-CS-84-1027, Stanford University, Department of Computer
  791.      Science, 1984.
  792.  14. [Knu86a] Donald E. Knuth.  A Torture Test for METAFONT.  Report
  793.      No. STAN-CS-86-1095, Stanford University, Department of Computer
  794.      Science, 1986.
  795.  15. [Knu86b] Donald E. Knuth.  `The TeXbook', volume A of `Computers
  796.      and Typesetting'.  Addison-Wesley, Reading, MA, USA, 1986.
  797.  16. [Knu86c] Donald E. Knuth.  `TeX: The Program', volume B of
  798.      `Computers and Typesetting'.  Addison-Wesley, Reading, MA, USA,
  799.      1986.
  800.  17. [Knu86d] Donald E. Knuth.  `The METAFONTbook', volume C of
  801.      `Computers and Typesetting'.  Addison-Wesley, Reading, MA, USA,
  802.      1986.
  803.  18. [Knu86e] Donald E. Knuth.  `METAFONT: The Program', volume D of
  804.      `Computers and   Typesetting'.  Addison-Wesley, Reading, MA, USA,
  805.      1986.
  806.  19. [Knu86f] Donald E. Knuth.  `Computer Modern Typefaces', volume E
  807.      of `Computers and   Typesetting'.  Addison-Wesley, Reading, MA,
  808.      USA, 1986.
  809.  20. [Knu89] Donald E. Knuth.  The errors of TeX.  `Software--Practice
  810.      and Experience', 19(7):607-681, July   1989.  This is an updated
  811.      version of iteKnuth:1988:ET.
  812.  21. [Knu90] Donald Knuth.  Virtual Fonts: More Fun for Grand Wizards.
  813.      `TUGboat', 11(1):13-23, April 1990.
  814.  22. [Knu92] Donald E. Knuth.  `Literate Programming'.  CSLI Lecture
  815.      Notes Number 27. Stanford University Center for the Study of
  816.      Language and Information, Stanford, CA, USA, 1992.
  817.  23. [Lam94] Leslie Lamport.  `LaTeX: A Document Preparation System:
  818.      User's Guide and Reference   Manual'.  Addison-Wesley, Reading,
  819.      MA, USA, second edition, 1994.
  820.  24. [Lia83] Franklin Mark Liang.  Word hy-phen-a-tion by com-pu-ter.
  821.      Technical Report STAN-CS-83-977, Stanford University, August 1983.
  822.  25. [Mac91] Pierre A. MacKay.  Looking at the pixels: Quality control
  823.      for 300 dpi laser printer fonts,   especially Metafonts.  In
  824.      Robert A. Morris and Jacques Andre, editors, `Raster Imaging and
  825.      Digital Typography II--Papers from the second RIDT meeting, held in
  826.       Boston, Oct. 14-16, 1991', pages 205-215, New York, 1991.
  827.      Cambridge   University Press.
  828.  26. [Spi89] Michael D. Spivak.  `LAMSTeX, The Synthesis'.  The
  829.      TeXplorators Corporation, 3701 W. Alabama, Suite 450-273, Houston,
  830.      TX   77027, USA, 1989.
  831.  27. [Spi90] Michael D. Spivak.  `The Joy of TeX--A Gourmet Guide to
  832.      Typesetting with the   AMSTeX macro package'.  American
  833.      Mathematical Society, Providence, RI, USA, 2nd revised edition,
  834.      1990.
  835.